IMPORTANT LAST MINUTE INFORMATION ABOUT DEVELOPING WITH CARBON
This document contains important information you need to know in order to use and develop for Carbon on Mac OS X.
Debugging with gdb and the zsh shell
• There are problems using the Unix shell /bin/zsh with gdb which will cause breakpoints to be ignored. Don't use zsh when debugging with gdb.
Launching CFM based Applications from HFS disks
• You cannot launch CFM based applications from HFS disks using the standard Mac OS X FileViewer.
• In order to launch CFM based executables from an HFS drive you will need to split the resource and data forks using the "UFS Converter" tool which is included with the Carbon development kit. This will create two items, the original file without resource fork and a directory of the same name with three trailing periods containing the resources. Be sure to move them together to avoid problems. You need to use /usr/Carbon/bin/LaunchCFMApp tool from the Unix command line.
• If you get an error telling you that the CFM-based application cannot be launched from the LaunchCFMApp tool, you can set the environment variable CFMDebugFull to 1 (setenv CFMDebugFull 1). This will print large amounts of debug information. Most helpful will be the information at the end of the output which will indicate if you are missing any shared libraries (error -2804). If you are, you need to get Carbonized versions and place them within a folder called "PEFLibraries" at the same level as your application. Another alternative is to link your Carbonized shared libraries directly into your application. Any file within the "PEFLibraries" will be blindly treated as a CFM shared library. Be sure that only CFM shared libraries go into this folder.
Navigation Services Known Problems
• AppleTalk zone and server browsing is not supported.
• When locating files on an HFS volume you will not see files you are looking for if you navigate to the HFS volume by use of the current hierarchy pop-up menu. Instead, use the Volumes pop-up (The one with the pointing finger) to navigate to the HFS volume first.
Cross Compiling with CodeWarrior
• Although it is covered in the "Carbon Porting Guide", remember that the tools for creating Mach-o executables are available from Metrowerks. You will not be able to build the "Mach-o" targets without these tools. You will be able to build the CarbonLib and LiteCarbonLib projects.
• In order to launch a cross compiled binary from the Workspace Manager you will have to explicitly set the executable bit for cross-compiled Mach-O apps. To do this use the attributes inspector from within the WorkSpace to set the execute permission.
• If you wish to use SimpleText as an example of how to do printing with Carbon, you will have to modify the Mach-o target of the Metrowerks project file.
- Copy the file /System/Library/Frameworks/CarbonPrinting.framework/Versions/A/CarbonPrinting to your development system.
- Change the type/creator to MDYL/CWIE.
- Add this file to the SimpleText.mcp file for the Mach-o target only. Re-link and proceed as before. Printing will now work in SimpleText.
Code Fragment Manager
• The current Mac OS X implementation looks within a "PEFLibraries" folder that is in the same folder as the app. You'll need to place any shared libraries that your app uses (other than CarbonLib) into this folder.
• If you need to debug Shared Libraries used/provided by your Application you will need to link them directly into your application in order to effectively debug them using gdb.
Open Transport
Overview of API changes
• Open Transport client context
Carbon introduces the new type, OTClientContextPtr, that represents the Open Transport client context. This new type is passed as an extra parameter to Open Transport API calls that allocate OT resources. Before Carbon, the determination of the Open Transport client context was performed by the Open Transport static libraries you had to link your application with. Because the determination of the Open Transport client context is now explicit the same Carbon binary can run on MacOS 8 and MacOS X and your application does not have to link with the static libraries.
They are two new APIs to explicitly create and destroy Open Transport client contexts:
OTAllocClientContext
OTFreeClientContext
• Callback as Universal Proc Pointers
Callback routines with Carbon should be passed as Universal Proc Pointers so they are new types of UPP that should be used instead of the raw proc pointers:
OTNotifyUPP
OTProcessUPP
OTListSearchUPP
Known bugs and limitations of Open Transport for MacOS X
• CloseOpenTransport is known to corrupt the memory pool. To workaround this problem the calls to CloseOpenTransport and OTFreeClientContext should be the very last ones of your application.
• Depending on the CPU and on the number of network interfaces the system have, OTInetGetInterfaceInfo will return the interfaces in an apparently random order. In addition it may return the loopback interface -- "lo0" in BSD parlance with address 127.0.0.1 -- as the primary interface (OTInetGetInterfaceInfo called with index 0). This might confuse some applications that rely on the primary interface to be an up and running Ethernet interface. The workaround is to call OTInetGetInterfaceInfo until you get an interface whose address is neither 127.0.0.1 nor 0.0.0.0.
• It is VERY important that you implement flow control correctly, as the buffer management is quite different from that of OT in Mac OS 8. You're likely to get kOTFlowErr under Mac OS X in circumstances where you would not under Mac OS 8.
• AppleTalk is not supported by Carbon even if the AppleTalk related APIs in the Open Transport headers are still present for Carbon.
• Only the I_FLUSH ioctl is supported.
• You have to have "root" privileges to use raw IP endpoints because a raw IP endpoint is opened by default as the privileged ICMP protocol -- raw IP protocols in the range 1 to 1024 require "root" privileges.
• You can create only simple configurations with just one protocol string in the path and no option. We also support the special path "tilisten,tcp".
• The Mac OS execution levels are not yet well emulated. Because notifications are issued from a thread you should not spend too much time in your notifier otherwise the notification thread may be suspended in favor of another thread (so you main application code may run while still inside the suspended notifier routine!). To workaround this problem, always protect data that is shared by code running at different execution levels.
• On MacOS X development systems, make sure to use the Open Transport header files found in "/System/Library/Framework/Carbon.framework/Headers/" and not the one in "/usr/Carbon/interfaces/". The ProjectBuilder Carbon project template does point to the correct directory.
Miscellaneous Known Problems (and associated bug tracking numbers)
2310703 fenv.h is wrapped in #if !forCarbon.
Workaround is to write your own header file; the symbols are exported in CarbonLib.
2329116 CreateEditTextControl weirdness
On MacOS X the text parameter seems to be ignored and I have to call SetControlData with the kControlEditTextTextTag. Same thing with Static Text. Passing the content of the Static Text in the text parameter of CreateStaticTextControl results in the first letter of the text missing. You have to call SetControlData to get the text correct.
2329208 Multiple Copies of Carbon Header files.
On Mac OS X, there are several copies of the Carbon headers. It is important that Applications (Carbon Clients) only rely upon the headers in /System/Library/Frameworks/Carbon.framework/Headers.
2329504 not setting the correct gestalt bits for Thread Manger
I get an assert from PowerPlant threads that the thread manager is not supported. This is because carbon is not setting the same gestalt bits as 8.x. which sets gestaltSpecificMatchSupport, which means the thread manager will match the exact stack size when looking in the thread pool (see ThreadMgr.c)
2330635 FindFolder with kDesktopFolderType doesn't work
FindFolder passed kDesktopFolderType doesn't return a valid folder on X, even if "create folder" is set to true - it always returns -120 directory not found. You will need to rely on another folder rather than the desktop folder for this release.
2330736 On MacOS X the Carbon clock control doesn't display the right time.
Well, actually, it seems to always display GMT. So, in once sense it is correct. "Even a broken clock is right twice a day..."
2307472 LMGetTEScrpLength and other LMGet/SetTE calls are missing in CarbonLib.
LMGetTEScrpHandle
LMGetTEScrpLength
LMSetTEScrpHandle
LMSetTEScrpLength
Don't rely on the use of these calls. While present, they are deprecated for Carbon and will not appear in future releases. See the Carbon Specficiation for more details.
2331124 Carbon apps sometimes hang messaging to the autodiskmount daemon.
After several invocations of a carbon app (tested with SimpleText) , Carbon applications appear to hang. After a little debugging it seems that we are waiting (forever) for a message response from the disk arbitration server. The workaround is to kill the autodiskmount daemon and invoke it again (/sbin/autodiskmount -a).
